---

FLAC/stream_encoder.h: stream encoder interface
[FLAC/_encoder.h: encoder interfaces]

This module contains the functions which implement the stream encoder. More...

Compounds
struct	FLAC__StreamEncoder
Typedefs
typedef FLAC__StreamEncoderWriteStatus(*	FLAC__StreamEncoderWriteCallback )(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)
typedef void(*	FLAC__StreamEncoderMetadataCallback )(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data)
Enumerations
enum	FLAC__StreamEncoderState {   FLAC__STREAM_ENCODER_OK = 0, FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR, FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA, FLAC__STREAM_ENCODER_INVALID_CALLBACK,   FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS, FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE, FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE, FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE,   FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER, FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION, FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH, FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH,   FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE, FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER, FLAC__STREAM_ENCODER_NOT_STREAMABLE, FLAC__STREAM_ENCODER_FRAMING_ERROR,   FLAC__STREAM_ENCODER_INVALID_METADATA, FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING, FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING, FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR,   FLAC__STREAM_ENCODER_ALREADY_INITIALIZED, FLAC__STREAM_ENCODER_UNINITIALIZED }
enum	FLAC__StreamEncoderWriteStatus { FLAC__STREAM_ENCODER_WRITE_STATUS_OK = 0, FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR }
Functions
FLAC__StreamEncoder *	FLAC__stream_encoder_new ()
void	FLAC__stream_encoder_delete (FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_set_verify (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_streamable_subset (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_do_mid_side_stereo (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_loose_mid_side_stereo (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_channels (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_bits_per_sample (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_sample_rate (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_blocksize (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_max_lpc_order (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_qlp_coeff_precision (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_do_qlp_coeff_prec_search (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_do_escape_coding (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_do_exhaustive_model_search (FLAC__StreamEncoder *encoder, FLAC__bool value)
FLAC__bool	FLAC__stream_encoder_set_min_residual_partition_order (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_max_residual_partition_order (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_rice_parameter_search_dist (FLAC__StreamEncoder *encoder, unsigned value)
FLAC__bool	FLAC__stream_encoder_set_total_samples_estimate (FLAC__StreamEncoder *encoder, FLAC__uint64 value)
FLAC__bool	FLAC__stream_encoder_set_metadata (FLAC__StreamEncoder *encoder, FLAC__StreamMetadata **metadata, unsigned num_blocks)
FLAC__bool	FLAC__stream_encoder_set_write_callback (FLAC__StreamEncoder *encoder, FLAC__StreamEncoderWriteCallback value)
FLAC__bool	FLAC__stream_encoder_set_metadata_callback (FLAC__StreamEncoder *encoder, FLAC__StreamEncoderMetadataCallback value)
FLAC__bool	FLAC__stream_encoder_set_client_data (FLAC__StreamEncoder *encoder, void *value)
FLAC__StreamEncoderState	FLAC__stream_encoder_get_state (const FLAC__StreamEncoder *encoder)
FLAC__StreamDecoderState	FLAC__stream_encoder_get_verify_decoder_state (const FLAC__StreamEncoder *encoder)
const char *	FLAC__stream_encoder_get_resolved_state_string (const FLAC__StreamEncoder *encoder)
void	FLAC__stream_encoder_get_verify_decoder_error_stats (const FLAC__StreamEncoder *encoder, FLAC__uint64 *absolute_sample, unsigned *frame_number, unsigned *channel, unsigned *sample, FLAC__int32 *expected, FLAC__int32 *got)
FLAC__bool	FLAC__stream_encoder_get_verify (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_streamable_subset (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_do_mid_side_stereo (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_loose_mid_side_stereo (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_channels (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_bits_per_sample (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_sample_rate (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_blocksize (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_max_lpc_order (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_qlp_coeff_precision (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_do_qlp_coeff_prec_search (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_do_escape_coding (const FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_get_do_exhaustive_model_search (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_min_residual_partition_order (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_max_residual_partition_order (const FLAC__StreamEncoder *encoder)
unsigned	FLAC__stream_encoder_get_rice_parameter_search_dist (const FLAC__StreamEncoder *encoder)
FLAC__uint64	FLAC__stream_encoder_get_total_samples_estimate (const FLAC__StreamEncoder *encoder)
FLAC__StreamEncoderState	FLAC__stream_encoder_init (FLAC__StreamEncoder *encoder)
void	FLAC__stream_encoder_finish (FLAC__StreamEncoder *encoder)
FLAC__bool	FLAC__stream_encoder_process (FLAC__StreamEncoder *encoder, const FLAC__int32 *const buffer[], unsigned samples)
FLAC__bool	FLAC__stream_encoder_process_interleaved (FLAC__StreamEncoder *encoder, const FLAC__int32 buffer[], unsigned samples)
Variables
const char *const	FLAC__StreamEncoderStateString []
const char *const	FLAC__StreamEncoderWriteStatusString []

---

Detailed Description

This module contains the functions which implement the stream encoder.

The basic usage of this encoder is as follows:

• The program creates an instance of an encoder using FLAC__stream_encoder_new().
• The program overrides the default settings and sets callbacks using FLAC__stream_encoder_set_*() functions.
• The program initializes the instance to validate the settings and prepare for encoding using FLAC__stream_encoder_init().
• The program calls FLAC__stream_encoder_process() or FLAC__stream_encoder_process_interleaved() to encode data, which subsequently calls the callbacks when there is encoder data ready to be written.
• The program finishes the encoding with FLAC__stream_encoder_finish(), which causes the encoder to encode any data still in its input pipe, call the metadata callback with the final encoding statistics, and finally reset the encoder to the uninitialized state.
• The instance may be used again or deleted with FLAC__stream_encoder_delete().

In more detail, the stream encoder functions similarly to the stream decoder, but has fewer callbacks and more options. Typically the user will create a new instance by calling FLAC__stream_encoder_new(), then set the necessary parameters and callbacks with FLAC__stream_encoder_set_*(), and initialize it by calling FLAC__stream_encoder_init().

Unlike the decoders, the stream encoder has many options that can affect the speed and compression ratio. When setting these parameters you should have some basic knowledge of the format (see the user-level documentation or the formal description). The FLAC__stream_encoder_set_*() functions themselves do not validate the values as many are interdependent. The FLAC__stream_encoder_init() function will do this, so make sure to pay attention to the state returned by FLAC__stream_encoder_init() to make sure that it is FLAC__STREAM_ENCODER_OK. Any parameters that are not set before FLAC__stream_encoder_init() will take on the defaults from the constructor.

The user must provide function pointers for the following callbacks:

• Write callback - This function is called by the encoder anytime there is raw encoded data to write. It may include metadata mixed with encoded audio frames and the data is not guaranteed to be aligned on frame or metadata block boundaries.
• Metadata callback - This function is called once at the end of encoding with the populated STREAMINFO structure. This is so file encoders can seek back to the beginning of the file and write the STREAMINFO block with the correct statistics after encoding (like minimum/maximum frame size).

The call to FLAC__stream_encoder_init() currently will also immediately call the write callback several times, once with the fLaC signature, and once for each encoded metadata block.

After initializing the instance, the user may feed audio data to the encoder in one of two ways:

• Channel separate, through FLAC__stream_encoder_process() - The user will pass an array of pointers to buffers, one for each channel, to the encoder, each of the same length. The samples need not be block-aligned.
• Channel interleaved, through FLAC__stream_encoder_process_interleaved() - The user will pass a single pointer to data that is channel-interleaved (i.e. channel0_sample0, channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). Again, the samples need not be block-aligned but they must be sample-aligned, i.e. the first value should be channel0_sample0 and the last value channelN_sampleM.

When the user is finished encoding data, it calls FLAC__stream_encoder_finish(), which causes the encoder to encode any data still in its input pipe, and call the metadata callback with the final encoding statistics. Then the instance may be deleted with FLAC__stream_encoder_delete() or initialized again to encode another stream.

For programs that write their own metadata, but that do not know the actual metadata until after encoding, it is advantageous to instruct the encoder to write a PADDING block of the correct size, so that instead of rewriting the whole stream after encoding, the program can just overwrite the PADDING block. If only the maximum size of the metadata is known, the program can write a slightly larger padding block, then split it after encoding.

Make sure you understand how lengths are calculated. All FLAC metadata blocks have a 4 byte header which contains the type and length. This length does not include the 4 bytes of the header. See the format page for the specification of metadata blocks and their lengths.

Note:

The "set" functions may only be called when the encoder is in the state FLAC__STREAM_ENCODER_UNINITIALIZED, i.e. after FLAC__stream_encoder_new() or FLAC__stream_encoder_finish(), but before FLAC__stream_encoder_init(). If this is the case they will return true, otherwise false.

Note:

FLAC__stream_encoder_finish() resets all settings to the constructor defaults, including the callbacks.

---

Typedef Documentation

typedef FLAC__StreamEncoderWriteStatus(* FLAC__StreamEncoderWriteCallback)(const FLAC__StreamEncoder *encoder, const FLAC__byte buffer[], unsigned bytes, unsigned samples, unsigned current_frame, void *client_data)

Signature for the write callback. See FLAC__stream_encoder_set_write_callback() for more info. Parameters: encoder  The encoder instance calling the callback. buffer  An array of encoded data of length bytes. bytes  The byte length of buffer. samples  The number of samples encoded by buffer. 0 has a special meaning; see FLAC__stream_encoder_set_write_callback(). current_frame  The number of the current frame being encoded. client_data  The callee's client data set through FLAC__stream_encoder_set_client_data(). Return values: FLAC__StreamDecoderWriteStatus  The callee's return status.

typedef void(* FLAC__StreamEncoderMetadataCallback)(const FLAC__StreamEncoder *encoder, const FLAC__StreamMetadata *metadata, void *client_data)

Signature for the metadata callback. See FLAC__stream_encoder_set_metadata_callback() for more info. Parameters: encoder  The encoder instance calling the callback. metadata  The final populated STREAMINFO block. client_data  The callee's client data set through FLAC__stream_encoder_set_client_data().

---

Enumeration Type Documentation

enum FLAC__StreamEncoderState

State values for a FLAC__StreamEncoder The encoder's state can be obtained by calling FLAC__stream_encoder_get_state(). Enumeration values: FLAC__STREAM_ENCODER_OK  The encoder is in the normal OK state. FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR  An error occurred in the underlying verify stream decoder; check FLAC__stream_encoder_get_verify_decoder_state(). FLAC__STREAM_ENCODER_VERIFY_MISMATCH_IN_AUDIO_DATA  The verify decoder detected a mismatch between the original audio signal and the decoded audio signal. FLAC__STREAM_ENCODER_INVALID_CALLBACK  The encoder was initialized before setting all the required callbacks. FLAC__STREAM_ENCODER_INVALID_NUMBER_OF_CHANNELS  The encoder has an invalid setting for number of channels. FLAC__STREAM_ENCODER_INVALID_BITS_PER_SAMPLE  The encoder has an invalid setting for bits-per-sample. FLAC supports 4-32 bps but the reference encoder currently supports only up to 24 bps. FLAC__STREAM_ENCODER_INVALID_SAMPLE_RATE  The encoder has an invalid setting for the input sample rate. FLAC__STREAM_ENCODER_INVALID_BLOCK_SIZE  The encoder has an invalid setting for the block size. FLAC__STREAM_ENCODER_INVALID_MAX_LPC_ORDER  The encoder has an invalid setting for the maximum LPC order. FLAC__STREAM_ENCODER_INVALID_QLP_COEFF_PRECISION  The encoder has an invalid setting for the precision of the quantized linear predictor coefficients. FLAC__STREAM_ENCODER_MID_SIDE_CHANNELS_MISMATCH  Mid/side coding was specified but the number of channels is not equal to 2. FLAC__STREAM_ENCODER_MID_SIDE_SAMPLE_SIZE_MISMATCH  Deprecated. FLAC__STREAM_ENCODER_ILLEGAL_MID_SIDE_FORCE  Loose mid/side coding was specified but mid/side coding was not. FLAC__STREAM_ENCODER_BLOCK_SIZE_TOO_SMALL_FOR_LPC_ORDER  The specified block size is less than the maximum LPC order. FLAC__STREAM_ENCODER_NOT_STREAMABLE  The encoder is bound to the "streamable subset" but other settings violate it. FLAC__STREAM_ENCODER_FRAMING_ERROR  An error occurred while writing the stream; usually, the write_callback returned an error. FLAC__STREAM_ENCODER_INVALID_METADATA  The metadata input to the encoder is invalid, in one of the following ways: FLAC__stream_encoder_set_metadata() was called with a null pointer but a block count > 0 One of the metadata blocks contains an undefined type It contains an illegal CUESHEET as checked by FLAC__format_cuesheet_is_legal() It contains an illegal SEEKTABLE as checked by FLAC__format_seektable_is_legal() It contains more than one SEEKTABLE block or more than one VORBIS_COMMENT block FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_ENCODING  An error occurred while writing the stream; usually, the write_callback returned an error. FLAC__STREAM_ENCODER_FATAL_ERROR_WHILE_WRITING  The write_callback returned an error. FLAC__STREAM_ENCODER_MEMORY_ALLOCATION_ERROR  Memory allocation failed. FLAC__STREAM_ENCODER_ALREADY_INITIALIZED  FLAC__stream_encoder_init() was called when the encoder was already initialized, usually because FLAC__stream_encoder_finish() was not called. FLAC__STREAM_ENCODER_UNINITIALIZED  The encoder is in the uninitialized state.

enum FLAC__StreamEncoderWriteStatus

Return values for the FLAC__StreamEncoder write callback. Enumeration values: FLAC__STREAM_ENCODER_WRITE_STATUS_OK  The write was OK and encoding can continue. FLAC__STREAM_ENCODER_WRITE_STATUS_FATAL_ERROR  An unrecoverable error occurred. The encoder will return from the process call.

---

Function Documentation

FLAC__StreamEncoder* FLAC__stream_encoder_new (    )

Create a new stream encoder instance. The instance is created with default settings; see the individual FLAC__stream_encoder_set_*() functions for each setting's default. Return values: FLAC__StreamEncoder  * NULL if there was an error allocating memory, else the new instance.

void FLAC__stream_encoder_delete (  FLAC__StreamEncoder *    encoder )

Free an encoder instance. Deletes the object pointed to by encoder. Parameters: encoder  A pointer to an existing encoder. Assertions: encoder != NULL

FLAC__bool FLAC__stream_encoder_set_verify (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set the "verify" flag. If true, the encoder will verify it's own encoded output by feeding it through an internal decoder and comparing the original signal against the decoded signal. If a mismatch occurs, the process call will return false. Note that this will slow the encoding process by the extra time required for decoding and comparison. Default Value: false Parameters: encoder  An encoder instance to set. value  Flag value (see above). Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_streamable_subset (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set the "streamable subset" flag. If true, the encoder will comply with the subset (see the format specification) and will check the settings during FLAC__stream_encoder_init() to see if all settings comply. If false, the settings may take advantage of the full range that the format allows. Make sure you know what it entails before setting this to false. Default Value: true Parameters: encoder  An encoder instance to set. value  Flag value (see above). Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_do_mid_side_stereo (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set to true to enable mid-side encoding on stereo input. The number of channels must be 2. Set to false to use only independent channel coding. Default Value: false Parameters: encoder  An encoder instance to set. value  Flag value (see above). Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_loose_mid_side_stereo (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set to true to enable adaptive switching between mid-side and left-right encoding on stereo input. The number of channels must be 2. Set to false to use exhaustive searching. In either case, the mid/side stereo setting must be true. Default Value: false Parameters: encoder  An encoder instance to set. value  Flag value (see above). Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_channels (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the number of channels to be encoded. Default Value: 2 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_bits_per_sample (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the sample resolution of the input to be encoded. Warning: Do not feed the encoder data that is wider than the value you set here or you will generate an invalid stream. Default Value: 16 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_sample_rate (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the sample rate (in Hz) of the input to be encoded. Default Value: 44100 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_blocksize (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the blocksize to use while encoding. Default Value: 1152 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_max_lpc_order (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the maximum LPC order, or 0 to use only the fixed predictors. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_qlp_coeff_precision (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the precision, in bits, of the quantized linear predictor coefficients, or 0 to let the encoder select it based on the blocksize. Note: In the current implementation, qlp_coeff_precision + bits_per_sample must be less than 32. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_do_qlp_coeff_prec_search (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set to false to use only the specified quantized linear predictor coefficient precision, or true to search neighboring precision values and use the best one. Default Value: false Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_do_escape_coding (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Deprecated. Setting this value has no effect. Default Value: false Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_do_exhaustive_model_search (  FLAC__StreamEncoder *    encoder, FLAC__bool    value )

Set to false to let the encoder estimate the best model order based on the residual signal energy, or true to force the encoder to evaluate all order models and select the best. Default Value: false Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_min_residual_partition_order (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the minimum partition order to search when coding the residual. This is used in tandem with FLAC__stream_encoder_set_max_residual_partition_order(). The partition order determines the context size in the residual. The context size will be approximately blocksize / (2 ^ order). Set both min and max values to 0 to force a single context, whose Rice parameter is based on the residual signal variance. Otherwise, set a min and max order, and the encoder will search all orders, using the mean of each context for its Rice parameter, and use the best. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_max_residual_partition_order (  FLAC__StreamEncoder *    encoder, unsigned    value )

Set the maximum partition order to search when coding the residual. This is used in tandem with FLAC__stream_encoder_set_min_residual_partition_order(). The partition order determines the context size in the residual. The context size will be approximately blocksize / (2 ^ order). Set both min and max values to 0 to force a single context, whose Rice parameter is based on the residual signal variance. Otherwise, set a min and max order, and the encoder will search all orders, using the mean of each context for its Rice parameter, and use the best. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_rice_parameter_search_dist (  FLAC__StreamEncoder *    encoder, unsigned    value )

Deprecated. Setting this value has no effect. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_total_samples_estimate (  FLAC__StreamEncoder *    encoder, FLAC__uint64    value )

Set an estimate of the total samples that will be encoded. This is merely an estimate and may be set to 0 if unknown. This value will be written to the STREAMINFO block before encoding, and can remove the need for the caller to rewrite the value later if the value is known before encoding. Default Value: 0 Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_metadata (  FLAC__StreamEncoder *    encoder, FLAC__StreamMetadata **    metadata, unsigned    num_blocks )

Set the metadata blocks to be emitted to the stream before encoding. A value of NULL, 0 implies no metadata; otherwise, supply an array of pointers to metadata blocks. The array is non-const since the encoder may need to change the is_last flag inside them. Otherwise, the encoder will not modify or free the blocks. It is up to the caller to free the metadata blocks after encoding. Note: The encoder stores only the metadata pointer; the passed-in array must survive at least until after FLAC__stream_encoder_init() returns. Do not modify the array or free the blocks until then. Note: The STREAMINFO block is always written and no STREAMINFO block may occur in the supplied array. Note: By default the encoder does not create a SEEKTABLE. If one is supplied in the metadata array it will be written verbatim. However by itself this is not very useful as the user will not know the stream offsets for the seekpoints ahead of time. You must use the seekable stream encoder to generate a legal seektable (see FLAC__seekable_stream_encoder_set_metadata()) Note: A VORBIS_COMMENT block may be supplied. The vendor string in it will be ignored. libFLAC will use it's own vendor string. libFLAC will not modify the passed-in VORBIS_COMMENT's vendor string, it will simply write it's own into the stream. If no VORBIS_COMMENT block is present in the metadata array, libFLAC will write an empty one, containing only the vendor string. Default Value: NULL, 0 Parameters: encoder  An encoder instance to set. metadata  See above. num_blocks  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_write_callback (  FLAC__StreamEncoder *    encoder, FLAC__StreamEncoderWriteCallback    value )

Set the write callback. The supplied function will be called by the encoder anytime there is raw encoded data ready to write. It may include metadata mixed with encoded audio frames and the data is not guaranteed to be aligned on frame or metadata block boundaries. The only duty of the callback is to write out the bytes worth of data in buffer to the current position in the output stream. The arguments samples and current_frame are purely informational. If samples is greater than 0, then current_frame will hold the current frame number that is being written; otherwise, the write callback is being called to write metadata. Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL value != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_metadata_callback (  FLAC__StreamEncoder *    encoder, FLAC__StreamEncoderMetadataCallback    value )

Set the metadata callback. The supplied function will be called once at the end of encoding with the populated STREAMINFO structure. This is so file encoders can seek back to the beginning of the file and write the STREAMINFO block with the correct statistics after encoding (like minimum/maximum frame size and total samples). Note: The callback is mandatory and must be set before initialization. Default Value: NULL Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL value != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__bool FLAC__stream_encoder_set_client_data (  FLAC__StreamEncoder *    encoder, void *    value )

Set the client data to be passed back to callbacks. This value will be supplied to callbacks in their client_data argument. Default Value: NULL Parameters: encoder  An encoder instance to set. value  See above. Assertions: encoder != NULL Return values: FLAC__bool  false if the encoder is already initialized, else true.

FLAC__StreamEncoderState FLAC__stream_encoder_get_state (  const FLAC__StreamEncoder *    encoder )

Get the current encoder state. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__StreamEncoderState  The current encoder state.

FLAC__StreamDecoderState FLAC__stream_encoder_get_verify_decoder_state (  const FLAC__StreamEncoder *    encoder )

Get the state of the verify stream decoder. Useful when the stream encoder state is FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__StreamDecoderState  The verify stream decoder state.

const char* FLAC__stream_encoder_get_resolved_state_string (  const FLAC__StreamEncoder *    encoder )

Get the current encoder state as a C string. This version automatically resolves FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR by getting the verify decoder's state. Parameters: encoder  A encoder instance to query. Assertions: encoder != NULL Return values: const  char * The encoder state as a C string. Do not modify the contents.

void FLAC__stream_encoder_get_verify_decoder_error_stats (  const FLAC__StreamEncoder *    encoder, FLAC__uint64 *    absolute_sample, unsigned *    frame_number, unsigned *    channel, unsigned *    sample, FLAC__int32 *    expected, FLAC__int32 *    got )

Get relevant values about the nature of a verify decoder error. Useful when the stream encoder state is FLAC__STREAM_ENCODER_VERIFY_DECODER_ERROR. The arguments should be addresses in which the stats will be returned, or NULL if value is not desired. Parameters: encoder  An encoder instance to query. absolute_sample  The absolute sample number of the mismatch. frame_number  The number of the frame in which the mismatch occurred. channel  The channel in which the mismatch occurred. sample  The number of the sample (relative to the frame) in which the mismatch occurred. expected  The expected value for the sample in question. got  The actual value returned by the decoder. Assertions: encoder != NULL

FLAC__bool FLAC__stream_encoder_get_verify (  const FLAC__StreamEncoder *    encoder )

Get the "verify" flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_verify().

FLAC__bool FLAC__stream_encoder_get_streamable_subset (  const FLAC__StreamEncoder *    encoder )

Get the "streamable subset" flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_streamable_subset().

FLAC__bool FLAC__stream_encoder_get_do_mid_side_stereo (  const FLAC__StreamEncoder *    encoder )

Get the "mid/side stereo coding" flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_get_do_mid_side_stereo().

FLAC__bool FLAC__stream_encoder_get_loose_mid_side_stereo (  const FLAC__StreamEncoder *    encoder )

Get the "adaptive mid/side switching" flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_loose_mid_side_stereo().

unsigned FLAC__stream_encoder_get_channels (  const FLAC__StreamEncoder *    encoder )

Get the number of input channels being processed. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_channels().

unsigned FLAC__stream_encoder_get_bits_per_sample (  const FLAC__StreamEncoder *    encoder )

Get the input sample resolution setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_bits_per_sample().

unsigned FLAC__stream_encoder_get_sample_rate (  const FLAC__StreamEncoder *    encoder )

Get the input sample rate setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_sample_rate().

unsigned FLAC__stream_encoder_get_blocksize (  const FLAC__StreamEncoder *    encoder )

Get the blocksize setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_blocksize().

unsigned FLAC__stream_encoder_get_max_lpc_order (  const FLAC__StreamEncoder *    encoder )

Get the maximum LPC order setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_max_lpc_order().

unsigned FLAC__stream_encoder_get_qlp_coeff_precision (  const FLAC__StreamEncoder *    encoder )

Get the quantized linear predictor coefficient precision setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_qlp_coeff_precision().

FLAC__bool FLAC__stream_encoder_get_do_qlp_coeff_prec_search (  const FLAC__StreamEncoder *    encoder )

Get the qlp coefficient precision search flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_do_qlp_coeff_prec_search().

FLAC__bool FLAC__stream_encoder_get_do_escape_coding (  const FLAC__StreamEncoder *    encoder )

Get the "escape coding" flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_do_escape_coding().

FLAC__bool FLAC__stream_encoder_get_do_exhaustive_model_search (  const FLAC__StreamEncoder *    encoder )

Get the exhaustive model search flag. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: FLAC__bool  See FLAC__stream_encoder_set_do_exhaustive_model_search().

unsigned FLAC__stream_encoder_get_min_residual_partition_order (  const FLAC__StreamEncoder *    encoder )

Get the minimum residual partition order setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_min_residual_partition_order().

unsigned FLAC__stream_encoder_get_max_residual_partition_order (  const FLAC__StreamEncoder *    encoder )

Get maximum residual partition order setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_max_residual_partition_order().

unsigned FLAC__stream_encoder_get_rice_parameter_search_dist (  const FLAC__StreamEncoder *    encoder )

Get the Rice parameter search distance setting. Parameters: encoder  An encoder instance to query. Assertions: encoder != NULL Return values: unsigned  See FLAC__stream_encoder_set_rice_parameter_search_dist().

FLAC__uint64 FLAC__stream_encoder_get_total_samples_estimate (  const FLAC__StreamEncoder *    encoder )

Get the previously set estimate of the total samples to be encoded. The encoder merely mimics back the value given to FLAC__stream_encoder_set_total_samples_estimate() since it has no other way of knowing how many samples the user will encode. Parameters: encoder  An encoder instance to set. Assertions: encoder != NULL Return values: FLAC__uint64  See FLAC__stream_encoder_get_total_samples_estimate().

FLAC__StreamEncoderState FLAC__stream_encoder_init (  FLAC__StreamEncoder *    encoder )

Initialize the encoder instance. Should be called after FLAC__stream_encoder_new() and FLAC__stream_encoder_set_*() but before FLAC__stream_encoder_process() or FLAC__stream_encoder_process_interleaved(). Will set and return the encoder state, which will be FLAC__STREAM_ENCODER_OK if initialization succeeded. The call to FLAC__stream_encoder_init() currently will also immediately call the write callback several times, once with the fLaC signature, and once for each encoded metadata block. Parameters: encoder  An uninitialized encoder instance. Assertions: encoder != NULL Return values: FLAC__StreamEncoderState  FLAC__STREAM_ENCODER_OK if initialization was successful; see FLAC__StreamEncoderState for the meanings of other return values.

void FLAC__stream_encoder_finish (  FLAC__StreamEncoder *    encoder )

Finish the encoding process. Flushes the encoding buffer, releases resources, resets the encoder settings to their defaults, and returns the encoder state to FLAC__STREAM_ENCODER_UNINITIALIZED. Note that this can generate one or more write callbacks before returning, and will generate a metadata callback. In the event of a prematurely-terminated encode, it is not strictly necessary to call this immediately before FLAC__stream_encoder_delete() but it is good practice to match every FLAC__stream_encoder_init() with a FLAC__stream_encoder_finish(). Parameters: encoder  An uninitialized encoder instance. Assertions: encoder != NULL

FLAC__bool FLAC__stream_encoder_process (  FLAC__StreamEncoder *    encoder, const FLAC__int32 *const    buffer[], unsigned    samples )

Submit data for encoding. This version allows you to supply the input data via an array of pointers, each pointer pointing to an array of samples samples representing one channel. The samples need not be block-aligned, but each channel should have the same number of samples. Parameters: encoder  An initialized encoder instance in the OK state. buffer  An array of pointers to each channel's signal. samples  The number of samples in one channel. Assertions: encoder != NULL FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK Return values: FLAC__bool  true if successful, else false; in this case, check the encoder state with FLAC__stream_encoder_get_state() to see what went wrong.

FLAC__bool FLAC__stream_encoder_process_interleaved (  FLAC__StreamEncoder *    encoder, const FLAC__int32    buffer[], unsigned    samples )

Submit data for encoding. This version allows you to supply the input data where the channels are interleaved into a single array (i.e. channel0_sample0, channel1_sample0, ... , channelN_sample0, channel0_sample1, ...). The samples need not be block-aligned but they must be sample-aligned, i.e. the first value should be channel0_sample0 and the last value channelN_sampleM. Parameters: encoder  An initialized encoder instance in the OK state. buffer  An array of channel-interleaved data (see above). samples  The number of samples in one channel, the same as for FLAC__stream_encoder_process(). For example, if encoding two channels, 1000 samples corresponds to a buffer of 2000 values. Assertions: encoder != NULL FLAC__stream_encoder_get_state(encoder) == FLAC__STREAM_ENCODER_OK Return values: FLAC__bool  true if successful, else false; in this case, check the encoder state with FLAC__stream_encoder_get_state() to see what went wrong.

---

Variable Documentation

const char* const FLAC__StreamEncoderStateString[]

Maps a FLAC__StreamEncoderState to a C string. Using a FLAC__StreamEncoderState as the index to this array will give the string equivalent. The contents should not be modified.

const char* const FLAC__StreamEncoderWriteStatusString[]

Maps a FLAC__StreamEncoderWriteStatus to a C string. Using a FLAC__StreamEncoderWriteStatus as the index to this array will give the string equivalent. The contents should not be modified.

---